<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <title>JavaScripTools Manual</title>
    <link rel="stylesheet" type="text/css" href="../../css/style.css">
</head>

<body>
<br>
<h1>JavaScripTools Manual</h1>
<h2>InputMask</h2>
<h3>Working with the SizeLimit</h3>
<p>A classic problem in web applications is to limit the number of characters on a textarea.
Many use something like <code>onkeyup="if (this.value.length &gt; 500) this.value = this.value.substring(0, 500)"</code>.
That's ugly.</p>
<p>SizeLimit is used just like all other masks, and handles both onkeyup and onblur events (many
people forget that the user can paste data with mouse). Aditionally, it can display a custom text on a given
html element or input field, or allow the user to perform custom actions. Look at the 
<a href="../../samples/sample_mask.html">samples</a> to see what SizeLimit can do.</p>
<p>The contructor arguments are (only the first two are mandatory):<ul>
<li>control: The control name or reference. Mandatory</li>
<li>maxLength: The maximum value length. Mandatory</li>
<li>output: A control or html element name or reference, where the outputText will be displayed. Optional.</li>
<li>outputText: A text that will be displayed on the output control. The default value is defined by the constant
JST_DEFAULT_LIMIT_OUTPUT_TEXT (check <a href="General_customizing.html">here</a> for details about default value 
customization). You can use the following variables:<ul>
    <li>${size}: Replaced by the current text size</li>
    <li>${left}: Replaced by the number of characters left</li>
    <li>${max}: Replaced by the maximum of characters that the control accepts</li>
</ul><b>Note</b>: If you are setting those variables in a JSP 2.0 page you would have to escape them, or
they would be interpreted as a server-side scoped variable. In that case, you can use \${size}, for example. 
The same may happen with other template processors that interprets ${...} as variable holders.</li>
<li>The others, updateFunction, keyUpFunction, blurFunction, are event handlers and are not recommended
to pass on the contructor, but as properties. For more information about custom event handlers, check the 
<a href="InputMask_intro.html">introduction</a>. <b>Important</b>: Unlike the other masks, the updateFunction
does not receive the SizeLimit instance, but the following arguments: The control instance, size the current size, 
the maximum size and the characters left. But, remember that it is evaluated by the SizeLimit instance, so, this
refers to the SizeLimit itself.</li>
</ul></p>
<p>Here are some examples (assuming a textarea named "text" and a div named "text_output"):</p>
<pre>//The simplest way
new SizeLimit("text", 500);

//Using an output
var limit = new SizeLimit("text", 500);
limit.output = "text_output";
limit.outputText = "${size}/${max}" //This would display sometihing like "127/500"

//Using a custom function to display the percent left
function onUpdate(control, size, max, left) {
    setValue("text_output", Math.round(size * 100 / max) + "%");
}
var limit = new SizeLimit("text", 500);
limit.updateFunction = onUpdate;
</pre>
<br><br>
<hr>
<table width="100%">
    <tr>
        <td width="33%" align="left"><b>Previous:</b><br><a href="InputMask_date.html">Working with the DateMask</a></td>
        <td width="34%" align="center"><a href="index.html">Table of Contents</a></td>
        <td width="33%" align="right"><b>Next:</b><br><a href="JavaScripTable_intro.html">Introduction to JavaScripTable</a></td>
    </tr>
</table>

</body>
</html>
